home *** CD-ROM | disk | FTP | other *** search
/ PC World 2008 February (DVD) / PCWorld_2008-02_DVD.iso / v cisle / PHP / PHP.exe / xampp-win32-1.6.5-installer.exe / php / PEAR / DB / Table.php < prev   
Encoding:
PHP Script  |  2007-12-20  |  75.9 KB  |  2,650 lines
  1. <?php
  2.  
  3. /**
  4. * 
  5. * DB_Table is a database API and data type SQL abstraction class.
  6. * 
  7. * DB_Table provides database API abstraction, data type abstraction,
  8. * automated SELECT, INSERT, and UPDATE queries, automated table
  9. * creation, automated validation of inserted/updated column values,
  10. * and automated creation of QuickForm elements based on the column
  11. * definitions.
  12. * 
  13. * @category DB
  14. * 
  15. * @package DB_Table
  16. *
  17. * @author Paul M. Jones <pmjones@php.net>
  18. * @author Mark Wiesemann <wiesemann@php.net>
  19. * 
  20. * @license http://www.gnu.org/copyleft/lesser.html LGPL
  21. * 
  22. * @version $Id: Table.php,v 1.69 2006/11/09 20:56:30 wiesemann Exp $
  23. *
  24. */
  25.  
  26. /**
  27. * Error code at instantiation time when the first parameter to the
  28. * constructor is not a PEAR DB object.
  29. */
  30. define('DB_TABLE_ERR_NOT_DB_OBJECT',    -1);
  31.  
  32. /**
  33. * Error code at instantiation time when the PEAR DB/MDB2 $phptype is not
  34. * supported by DB_Table.
  35. */
  36. define('DB_TABLE_ERR_PHPTYPE',          -2);
  37.  
  38. /**
  39. * Error code when you call select() or selectResult() and the first
  40. * parameter does not match any of the $this->sql keys.
  41. */
  42. define('DB_TABLE_ERR_SQL_UNDEF',        -3);
  43.  
  44. /**
  45. * Error code when you try to insert data to a column that is not in the
  46. * $this->col array.
  47. */
  48. define('DB_TABLE_ERR_INS_COL_NOMAP',    -4);
  49.  
  50. /**
  51. * Error code when you try to insert data, and that data does not have a
  52. * column marked as 'require' in the $this->col array.
  53. */
  54. define('DB_TABLE_ERR_INS_COL_REQUIRED', -5);
  55.  
  56. /**
  57. * Error code when auto-validation fails on data to be inserted.
  58. */
  59. define('DB_TABLE_ERR_INS_DATA_INVALID', -6);
  60.  
  61. /**
  62. * Error code when you try to update data to a column that is not in the
  63. * $this->col array.
  64. */
  65. define('DB_TABLE_ERR_UPD_COL_NOMAP',    -7);
  66.  
  67. /**
  68. * Error code when you try to update data, and that data does not have a
  69. * column marked as 'require' in the $this->col array.
  70. */
  71. define('DB_TABLE_ERR_UPD_COL_REQUIRED', -8);
  72.  
  73. /**
  74. * Error code when auto-validation fails on update data.
  75. */
  76. define('DB_TABLE_ERR_UPD_DATA_INVALID', -9);
  77.  
  78. /**
  79. * Error code when you use a create() flag that is not recognized (must
  80. * be 'safe', 'drop', 'verify' or boolean false.
  81. */
  82. define('DB_TABLE_ERR_CREATE_FLAG',      -10);
  83.  
  84. /**
  85. * Error code at create() time when you define an index in $this->idx
  86. * that has no columns.
  87. */
  88. define('DB_TABLE_ERR_IDX_NO_COLS',      -11);
  89.  
  90. /**
  91. * Error code at create() time when you define an index in $this->idx
  92. * that refers to a column that does not exist in the $this->col array.
  93. */
  94. define('DB_TABLE_ERR_IDX_COL_UNDEF',    -12);
  95.  
  96. /**
  97. * Error code at create() time when you define a $this->idx index type
  98. * that is not recognized (must be 'normal' or 'unique').
  99. */
  100. define('DB_TABLE_ERR_IDX_TYPE',         -13);
  101.  
  102. /**
  103. * Error code at create() time when you have an error in a 'char' or
  104. * 'varchar' definition in $this->col (usually because 'size' is wrong).
  105. */
  106. define('DB_TABLE_ERR_DECLARE_STRING',   -14);
  107.  
  108. /**
  109. * Error code at create() time when you have an error in a 'decimal'
  110. * definition (usually becuase the 'size' or 'scope' are wrong).
  111. */
  112. define('DB_TABLE_ERR_DECLARE_DECIMAL',  -15);
  113.  
  114. /**
  115. * Error code at create() time when you define a column in $this->col
  116. * with an unrecognized 'type'.
  117. */
  118. define('DB_TABLE_ERR_DECLARE_TYPE',     -16);
  119.  
  120. /**
  121. * Error code at validation time when a column in $this->col has an
  122. * unrecognized 'type'.
  123. */
  124. define('DB_TABLE_ERR_VALIDATE_TYPE',    -17);
  125.  
  126. /**
  127. * Error code at create() time when you define a column in $this->col
  128. * with an invalid column name (usually because it's a reserved keyword).
  129. */
  130. define('DB_TABLE_ERR_DECLARE_COLNAME',  -18);
  131.  
  132. /**
  133. * Error code at create() time when you define an index in $this->idx
  134. * with an invalid index name (usually because it's a reserved keyword).
  135. */
  136. define('DB_TABLE_ERR_DECLARE_IDXNAME',  -19);
  137.  
  138. /**
  139. * Error code at create() time when you define an index in $this->idx
  140. * that refers to a CLOB column.
  141. */
  142. define('DB_TABLE_ERR_IDX_COL_CLOB',     -20);
  143.  
  144. /**
  145. * Error code at create() time when you define a column name that is
  146. * more than 30 chars long (an Oracle restriction).
  147. */
  148. define('DB_TABLE_ERR_DECLARE_STRLEN',   -21);
  149.  
  150. /**
  151. * Error code at create() time when the index name ends up being more
  152. * than 30 chars long (an Oracle restriction).
  153. */
  154. define('DB_TABLE_ERR_IDX_STRLEN',       -22);
  155.  
  156. /**
  157. * Error code at create() time when the table name is more than 30 chars
  158. * long (an Oracle restriction).
  159. */
  160. define('DB_TABLE_ERR_TABLE_STRLEN',     -23);
  161.  
  162. /**
  163. * Error code at nextID() time when the sequence name is more than 30
  164. * chars long (an Oracle restriction).
  165. */
  166. define('DB_TABLE_ERR_SEQ_STRLEN',       -24);
  167.  
  168. /**
  169. * Error code at verify() time when the table does not exist in the
  170. * database.
  171. */
  172. define('DB_TABLE_ERR_VER_TABLE_MISSING', -25);
  173.  
  174. /**
  175. * Error code at verify() time when the column does not exist in the
  176. * database table.
  177. */
  178. define('DB_TABLE_ERR_VER_COLUMN_MISSING', -26);
  179.  
  180. /**
  181. * Error code at verify() time when the column type does not match the
  182. * type specified in the column declaration.
  183. */
  184. define('DB_TABLE_ERR_VER_COLUMN_TYPE',  -27);
  185.  
  186. /**
  187. * Error code at instantiation time when the column definition array
  188. * does not contain at least one column.
  189. */
  190. define('DB_TABLE_ERR_NO_COLS',          -28);
  191.  
  192. /**
  193. * Error code at verify() time when an index cannot be found in the
  194. * database table.
  195. */
  196. define('DB_TABLE_ERR_VER_IDX_MISSING',   -29);
  197.  
  198. /**
  199. * Error code at verify() time when an index does not contain all
  200. * columns that it should contain.
  201. */
  202. define('DB_TABLE_ERR_VER_IDX_COL_MISSING', -30);
  203.  
  204. /**
  205. * Error code at instantiation time when a creation mode
  206. * is not available for a phptype.
  207. */
  208. define('DB_TABLE_ERR_CREATE_PHPTYPE', -31);
  209.  
  210. /**
  211. * Error code at create() time when you define more than one primary key
  212. * in $this->idx.
  213. */
  214. define('DB_TABLE_ERR_DECLARE_PRIMARY', -32);
  215.  
  216. /**
  217. * Error code at create() time when a primary key is defined in $this->idx
  218. * and SQLite is used (SQLite does not support primary keys).
  219. */
  220. define('DB_TABLE_ERR_DECLARE_PRIM_SQLITE', -33);
  221.  
  222. /**
  223. * Error code at alter() time when altering a table field is not possible
  224. * (e.g. because MDB2 has no support for the change or because the DBMS
  225. * does not support the change).
  226. */
  227. define('DB_TABLE_ERR_ALTER_TABLE_IMPOS', -34);
  228.  
  229. /**
  230. * Error code at alter() time when altering a(n) index/constraint is not possible
  231. * (e.g. because MDB2 has no support for the change or because the DBMS
  232. * does not support the change).
  233. */
  234. define('DB_TABLE_ERR_ALTER_INDEX_IMPOS', -35);
  235.  
  236. /**
  237. * The PEAR class for errors
  238. */
  239. require_once 'PEAR.php';
  240.  
  241. /**
  242. * The Date class for recasting date and time values
  243. */
  244. require_once 'DB/Table/Date.php';
  245.  
  246.  
  247. /**
  248. * DB_Table supports these RDBMS engines and their various native data
  249. * types; we need these here instead of in Manager.php because the
  250. * initial array key tells us what databases are supported.
  251. */
  252. $GLOBALS['_DB_TABLE']['type'] = array(
  253.     'fbsql' => array(
  254.         'boolean'   => 'DECIMAL(1,0)',
  255.         'char'      => 'CHAR',
  256.         'varchar'   => 'VARCHAR',
  257.         'smallint'  => 'SMALLINT',
  258.         'integer'   => 'INTEGER',
  259.         'bigint'    => 'LONGINT',
  260.         'decimal'   => 'DECIMAL',
  261.         'single'    => 'REAL',
  262.         'double'    => 'DOUBLE PRECISION',
  263.         'clob'      => 'CLOB',
  264.         'date'      => 'CHAR(10)',
  265.         'time'      => 'CHAR(8)',
  266.         'timestamp' => 'CHAR(19)'
  267.     ),
  268.     'ibase' => array(
  269.         'boolean'   => 'DECIMAL(1,0)',
  270.         'char'      => 'CHAR',
  271.         'varchar'   => 'VARCHAR',
  272.         'smallint'  => 'SMALLINT',
  273.         'integer'   => 'INTEGER',
  274.         'bigint'    => 'BIGINT',
  275.         'decimal'   => 'DECIMAL',
  276.         'single'    => 'FLOAT',
  277.         'double'    => 'DOUBLE PRECISION',
  278.         'clob'      => 'BLOB SUB_TYPE 1',
  279.         'date'      => 'DATE',
  280.         'time'      => 'TIME',
  281.         'timestamp' => 'TIMESTAMP'
  282.     ),
  283.     'mssql' => array(
  284.         'boolean'   => 'DECIMAL(1,0)',
  285.         'char'      => 'CHAR',
  286.         'varchar'   => 'VARCHAR',
  287.         'smallint'  => 'SMALLINT',
  288.         'integer'   => 'INTEGER',
  289.         'bigint'    => 'BIGINT',
  290.         'decimal'   => 'DECIMAL',
  291.         'single'    => 'REAL',
  292.         'double'    => 'FLOAT',
  293.         'clob'      => 'TEXT',
  294.         'date'      => 'CHAR(10)',
  295.         'time'      => 'CHAR(8)',
  296.         'timestamp' => 'CHAR(19)'
  297.     ),
  298.     'mysql' => array(
  299.         'boolean'   => 'DECIMAL(1,0)',
  300.         'char'      => 'CHAR',
  301.         'varchar'   => 'VARCHAR',
  302.         'smallint'  => 'SMALLINT',
  303.         'integer'   => 'INTEGER',
  304.         'bigint'    => 'BIGINT',
  305.         'decimal'   => 'DECIMAL',
  306.         'single'    => 'FLOAT',
  307.         'double'    => 'DOUBLE',
  308.         'clob'      => 'LONGTEXT',
  309.         'date'      => 'CHAR(10)',
  310.         'time'      => 'CHAR(8)',
  311.         'timestamp' => 'CHAR(19)'
  312.     ),
  313.     'mysqli' => array(
  314.         'boolean'   => 'DECIMAL(1,0)',
  315.         'char'      => 'CHAR',
  316.         'varchar'   => 'VARCHAR',
  317.         'smallint'  => 'SMALLINT',
  318.         'integer'   => 'INTEGER',
  319.         'bigint'    => 'BIGINT',
  320.         'decimal'   => 'DECIMAL',
  321.         'single'    => 'FLOAT',
  322.         'double'    => 'DOUBLE',
  323.         'clob'      => 'LONGTEXT',
  324.         'date'      => 'CHAR(10)',
  325.         'time'      => 'CHAR(8)',
  326.         'timestamp' => 'CHAR(19)'
  327.     ),
  328.     'oci8' => array(
  329.         'boolean'   => 'NUMBER(1)',
  330.         'char'      => 'CHAR',
  331.         'varchar'   => 'VARCHAR2',
  332.         'smallint'  => 'NUMBER(6)',
  333.         'integer'   => 'NUMBER(11)',
  334.         'bigint'    => 'NUMBER(19)',
  335.         'decimal'   => 'NUMBER',
  336.         'single'    => 'REAL',
  337.         'double'    => 'DOUBLE PRECISION',
  338.         'clob'      => 'CLOB',
  339.         'date'      => 'CHAR(10)',
  340.         'time'      => 'CHAR(8)',
  341.         'timestamp' => 'CHAR(19)'
  342.     ),
  343.     'pgsql' => array(
  344.         'boolean'   => 'DECIMAL(1,0)',
  345.         'char'      => 'CHAR',
  346.         'varchar'   => 'VARCHAR',
  347.         'smallint'  => 'SMALLINT',
  348.         'integer'   => 'INTEGER',
  349.         'bigint'    => 'BIGINT',
  350.         'decimal'   => 'DECIMAL',
  351.         'single'    => 'REAL',
  352.         'double'    => 'DOUBLE PRECISION',
  353.         'clob'      => 'TEXT',
  354.         'date'      => 'CHAR(10)',
  355.         'time'      => 'CHAR(8)',
  356.         'timestamp' => 'CHAR(19)'
  357.     ),
  358.     'sqlite' => array(
  359.         'boolean'   => 'BOOLEAN',
  360.         'char'      => 'CHAR',
  361.         'varchar'   => 'VARCHAR',
  362.         'smallint'  => 'SMALLINT',
  363.         'integer'   => 'INTEGER',
  364.         'bigint'    => 'BIGINT',
  365.         'decimal'   => 'NUMERIC',
  366.         'single'    => 'FLOAT',
  367.         'double'    => 'DOUBLE',
  368.         'clob'      => 'CLOB',
  369.         'date'      => 'DATE',
  370.         'time'      => 'TIME',
  371.         'timestamp' => 'TIMESTAMP'
  372.     )
  373. );
  374.  
  375.  
  376. /** 
  377.   * US-English default error messages. If you want to internationalize, you can
  378.   * set the translated messages via $GLOBALS['_DB_TABLE']['error']. You can also
  379.   * use DB_Table::setErrorMessage(). Examples:
  380.   * 
  381.   * <code>
  382.   * (1) $GLOBALS['_DB_TABLE]['error'] = array(DB_TABLE_ERR_PHPTYPE   => '...',
  383.   *                                           DB_TABLE_ERR_SQL_UNDEF => '...');
  384.   * (2) DB_Table::setErrorMessage(DB_TABLE_ERR_PHPTYPE,   '...');
  385.   *     DB_Table::setErrorMessage(DB_TABLE_ERR_SQL_UNDEF, '...');
  386.   * (3) DB_Table::setErrorMessage(array(DB_TABLE_ERR_PHPTYPE   => '...');
  387.   *                                     DB_TABLE_ERR_SQL_UNDEF => '...');
  388.   * (4) $obj =& new DB_Table();
  389.   *     $obj->setErrorMessage(DB_TABLE_ERR_PHPTYPE,   '...');
  390.   *     $obj->setErrorMessage(DB_TABLE_ERR_SQL_UNDEF, '...');
  391.   * (5) $obj =& new DB_Table();
  392.   *     $obj->setErrorMessage(array(DB_TABLE_ERR_PHPTYPE   => '...');
  393.   *                                 DB_TABLE_ERR_SQL_UNDEF => '...');
  394.   * </code>
  395.   * 
  396.   * For errors that can occur with-in the constructor call (i.e. e.g. creating
  397.   * or altering the database table), only the code from examples (1) to (3)
  398.   * will alter the default error messages early enough. For errors that can
  399.   * occur later, examples (4) and (5) are also valid.
  400.   */
  401. $GLOBALS['_DB_TABLE']['default_error'] = array(
  402.     DB_TABLE_ERR_NOT_DB_OBJECT       => 'First parameter must be a DB/MDB2 object',
  403.     DB_TABLE_ERR_PHPTYPE             => 'DB/MDB2 phptype (or dbsyntax) not supported',
  404.     DB_TABLE_ERR_SQL_UNDEF           => 'Select key not in map',
  405.     DB_TABLE_ERR_INS_COL_NOMAP       => 'Insert column not in map',
  406.     DB_TABLE_ERR_INS_COL_REQUIRED    => 'Insert data must be set and non-null for column',
  407.     DB_TABLE_ERR_INS_DATA_INVALID    => 'Insert data not valid for column',
  408.     DB_TABLE_ERR_UPD_COL_NOMAP       => 'Update column not in map',
  409.     DB_TABLE_ERR_UPD_COL_REQUIRED    => 'Update column must be set and non-null',
  410.     DB_TABLE_ERR_UPD_DATA_INVALID    => 'Update data not valid for column',
  411.     DB_TABLE_ERR_CREATE_FLAG         => 'Create flag not valid',
  412.     DB_TABLE_ERR_IDX_NO_COLS         => 'No columns for index',
  413.     DB_TABLE_ERR_IDX_COL_UNDEF       => 'Column not in map for index',
  414.     DB_TABLE_ERR_IDX_TYPE            => 'Type not valid for index',
  415.     DB_TABLE_ERR_DECLARE_STRING      => 'String column declaration not valid',
  416.     DB_TABLE_ERR_DECLARE_DECIMAL     => 'Decimal column declaration not valid',
  417.     DB_TABLE_ERR_DECLARE_TYPE        => 'Column type not valid',
  418.     DB_TABLE_ERR_VALIDATE_TYPE       => 'Cannot validate for unknown type on column',
  419.     DB_TABLE_ERR_DECLARE_COLNAME     => 'Column name not valid',
  420.     DB_TABLE_ERR_DECLARE_IDXNAME     => 'Index name not valid',
  421.     DB_TABLE_ERR_DECLARE_TYPE        => 'Column type not valid',
  422.     DB_TABLE_ERR_IDX_COL_CLOB        => 'CLOB column not allowed for index',
  423.     DB_TABLE_ERR_DECLARE_STRLEN      => 'Column name too long, 30 char max',
  424.     DB_TABLE_ERR_IDX_STRLEN          => 'Index name too long, 30 char max',
  425.     DB_TABLE_ERR_TABLE_STRLEN        => 'Table name too long, 30 char max',
  426.     DB_TABLE_ERR_SEQ_STRLEN          => 'Sequence name too long, 30 char max',
  427.     DB_TABLE_ERR_VER_TABLE_MISSING   => 'Verification failed: table does not exist',
  428.     DB_TABLE_ERR_VER_COLUMN_MISSING  => 'Verification failed: column does not exist',
  429.     DB_TABLE_ERR_VER_COLUMN_TYPE     => 'Verification failed: wrong column type',
  430.     DB_TABLE_ERR_NO_COLS             => 'Column definition array may not be empty',
  431.     DB_TABLE_ERR_VER_IDX_MISSING     => 'Verification failed: index does not exist',
  432.     DB_TABLE_ERR_VER_IDX_COL_MISSING => 'Verification failed: index does not contain all specified cols',
  433.     DB_TABLE_ERR_CREATE_PHPTYPE      => 'Creation mode is not supported for this phptype',
  434.     DB_TABLE_ERR_DECLARE_PRIMARY     => 'Only one primary key is allowed',
  435.     DB_TABLE_ERR_DECLARE_PRIM_SQLITE => 'SQLite does not support primary keys',
  436.     DB_TABLE_ERR_ALTER_TABLE_IMPOS   => 'Alter table failed: changing the field type not possible',
  437.     DB_TABLE_ERR_ALTER_INDEX_IMPOS   => 'Alter table failed: changing the index/constraint not possible'
  438. );
  439.  
  440. // merge default and user-defined error messages
  441. if (!isset($GLOBALS['_DB_TABLE']['error'])) {
  442.     $GLOBALS['_DB_TABLE']['error'] = array();
  443. }
  444. foreach ($GLOBALS['_DB_TABLE']['default_error'] as $code => $message) {
  445.     if (!array_key_exists($code, $GLOBALS['_DB_TABLE']['error'])) {
  446.         $GLOBALS['_DB_TABLE']['error'][$code] = $message;
  447.     }
  448. }
  449.  
  450. /**
  451. * 
  452. * DB_Table is a database API and data type SQL abstraction class.
  453. * 
  454. * DB_Table provides database API abstraction, data type abstraction,
  455. * automated SELECT, INSERT, and UPDATE queries, automated table
  456. * creation, automated validation of inserted/updated column values,
  457. * and automated creation of QuickForm elemnts based on the column
  458. * definitions.
  459. * 
  460. * @category DB
  461. * 
  462. * @package DB_Table
  463. * 
  464. * @author Paul M. Jones <pmjones@php.net>
  465. * @author Mark Wiesemann <wiesemann@php.net>
  466. * 
  467. * @version 1.4.0
  468. *
  469. */
  470.  
  471. class DB_Table {
  472.     
  473.     
  474.     /**
  475.     * 
  476.     * The PEAR DB/MDB2 object that connects to the database.
  477.     * 
  478.     * @access public
  479.     * 
  480.     * @var object
  481.     * 
  482.     */
  483.     
  484.     var $db = null;
  485.     
  486.     
  487.     /**
  488.     * 
  489.     * The backend type
  490.     * 
  491.     * @access public
  492.     * 
  493.     * @var string
  494.     * 
  495.     */
  496.     
  497.     var $backend = null;
  498.     
  499.     
  500.     /**
  501.     * 
  502.     * The table or view in the database to which this object binds.
  503.     * 
  504.     * @access public
  505.     * 
  506.     * @var string
  507.     * 
  508.     */
  509.     
  510.     var $table = null;
  511.     
  512.     
  513.     /**
  514.     * 
  515.     * Associative array of column definitions.
  516.     * 
  517.     * @access public
  518.     * 
  519.     * @var array
  520.     * 
  521.     */
  522.     
  523.     var $col = array();
  524.     
  525.     
  526.     /**
  527.     * 
  528.     * Associative array of index definitions.
  529.     * 
  530.     * @access public
  531.     * 
  532.     * @var array
  533.     * 
  534.     */
  535.     
  536.     var $idx = array();
  537.     
  538.     
  539.     /**
  540.     * 
  541.     * Baseline SELECT maps for select(), selectResult(), selectCount().
  542.     * 
  543.     * @access public
  544.     * 
  545.     * @var array
  546.     * 
  547.     */
  548.     
  549.     var $sql = array();
  550.     
  551.     
  552.     /**
  553.     * 
  554.     * Whether or not to automatically validate data at insert-time.
  555.     * 
  556.     * @access private
  557.     * 
  558.     * @var bool
  559.     * 
  560.     */
  561.     
  562.     var $_valid_insert = true;
  563.     
  564.     
  565.     /**
  566.     * 
  567.     * Whether or not to automatically validate data at update-time.
  568.     * 
  569.     * @access private
  570.     * 
  571.     * @var bool
  572.     * 
  573.     */
  574.     
  575.     var $_valid_update = true;
  576.     
  577.     
  578.     /**
  579.     * 
  580.     * When calling select() and selectResult(), use this fetch mode (usually
  581.     * a DB_FETCHMODE_* constant).  If null, uses whatever is set in the $db
  582.     * PEAR DB/MDB2 object.
  583.     * 
  584.     * @access public
  585.     * 
  586.     * @var int
  587.     * 
  588.     */
  589.     
  590.     var $fetchmode = null;
  591.     
  592.     
  593.     /**
  594.     * 
  595.     * When fetchmode is DB_FETCHMODE_OBJECT, use this class for each
  596.     * returned row.  If null, uses whatever is set in the $db
  597.     * PEAR DB/MDB2 object.
  598.     * 
  599.     * @access public
  600.     * 
  601.     * @var string
  602.     * 
  603.     */
  604.     
  605.     var $fetchmode_object_class = null;
  606.     
  607.     
  608.     /**
  609.     * 
  610.     * If there is an error on instantiation, this captures that error.
  611.     *
  612.     * This property is used only for errors encountered in the constructor
  613.     * at instantiation time.  To check if there was an instantiation error...
  614.     *
  615.     * <code>
  616.     * $obj =& new DB_Table();
  617.     * if ($obj->error) {
  618.     *     // ... error handling code here ...
  619.     * }
  620.     * </code>
  621.     * 
  622.     * @var object PEAR_Error
  623.     * 
  624.     */
  625.     
  626.     var $error = null;
  627.  
  628.  
  629.     /**
  630.     * 
  631.     * Whether or not to automatically recast data at insert- and update-time.
  632.     * 
  633.     * @access private
  634.     * 
  635.     * @var bool
  636.     * 
  637.     */
  638.     
  639.     var $_auto_recast = true;
  640.     
  641.     
  642.     /**
  643.     * 
  644.     * Specialized version of throwError() modeled on PEAR_Error.
  645.     * 
  646.     * Throws a PEAR_Error with a DB_Table error message based on a
  647.     * DB_Table constant error code.
  648.     * 
  649.     * @static
  650.     * 
  651.     * @access public
  652.     * 
  653.     * @param string $code A DB_Table error code constant.
  654.     * 
  655.     * @param string $extra Extra text for the error (in addition to the 
  656.     * regular error message).
  657.     * 
  658.     * @return object PEAR_Error
  659.     * 
  660.     */
  661.     
  662.     function &throwError($code, $extra = null)
  663.     {
  664.         // get the error message text based on the error code
  665.         $text = $GLOBALS['_DB_TABLE']['error'][$code];
  666.         
  667.         // add any additional error text
  668.         if ($extra) {
  669.             $text .= ' ' . $extra;
  670.         }
  671.         
  672.         // done!
  673.         $error = PEAR::throwError($text, $code);
  674.         return $error;
  675.     }
  676.     
  677.     
  678.     /**
  679.     * 
  680.     * Constructor.
  681.     * 
  682.     * If there is an error on instantiation, $this->error will be 
  683.     * populated with the PEAR_Error.
  684.     * 
  685.     * @access public
  686.     * 
  687.     * @param object &$db A PEAR DB/MDB2 object.
  688.     * 
  689.     * @param string $table The table name to connect to in the database.
  690.     * 
  691.     * @param mixed $create The automatic table creation mode to pursue:
  692.     * - boolean false to not attempt creation
  693.     * - 'safe' to create the table only if it does not exist
  694.     * - 'drop' to drop any existing table with the same name and re-create it
  695.     * - 'verify' to check whether the table exists, whether all the columns
  696.     *   exist, whether the columns have the right type, and whether the indexes
  697.     *   exist and have the right type
  698.     * - 'alter' does the same as 'safe' if the table does not exist; if it
  699.     *   exists, a verification for columns existence, the column types, the
  700.     *   indexes existence, and the indexes types will be performed and the
  701.     *   table schema will be modified if needed
  702.     * 
  703.     * @return object DB_Table
  704.     * 
  705.     */
  706.     
  707.     function DB_Table(&$db, $table, $create = false)
  708.     {
  709.         // is the first argument a DB/MDB2 object?
  710.         $this->backend = null;
  711.         if (is_subclass_of($db, 'db_common')) {
  712.             $this->backend = 'db';
  713.         } elseif (is_subclass_of($db, 'mdb2_driver_common')) {
  714.             $this->backend = 'mdb2';
  715.         }
  716.  
  717.         if (is_null($this->backend)) {
  718.             $this->error =& DB_Table::throwError(DB_TABLE_ERR_NOT_DB_OBJECT);
  719.             return;
  720.         }
  721.         
  722.         // array with column definition may not be empty        
  723.         if (! isset($this->col) || is_null($this->col) ||
  724.                 (is_array($this->col) && count($this->col) === 0)) {
  725.             $this->error =& DB_Table::throwError(DB_TABLE_ERR_NO_COLS);
  726.             return;
  727.         }
  728.  
  729.         // set the class properties
  730.         $this->db =& $db;
  731.         $this->table = $table;
  732.         
  733.         // is the RDBMS supported?
  734.         list($phptype, $dbsyntax) = DB_Table::getPHPTypeAndDBSyntax($db);
  735.         if (! DB_Table::supported($phptype, $dbsyntax)) {
  736.             $this->error =& DB_Table::throwError(
  737.                 DB_TABLE_ERR_PHPTYPE,
  738.                 "({$db->phptype})"
  739.             );
  740.             return;
  741.         }
  742.  
  743.         // load MDB2_Extended module
  744.         if ($this->backend == 'mdb2') {
  745.             $this->db->loadModule('Extended', null, false);
  746.         }
  747.  
  748.         // should we attempt table creation?
  749.         if ($create) {
  750.  
  751.             if ($this->backend == 'mdb2') {
  752.                 $this->db->loadModule('Manager');
  753.             }
  754.  
  755.             // check whether the chosen mode is supported
  756.             list($phptype,) = DB_Table::getPHPTypeAndDBSyntax($this->db);
  757.             $mode_supported = DB_Table::modeSupported($create, $phptype);
  758.             if (PEAR::isError($mode_supported)) {
  759.                 $this->error =& $mode_supported;
  760.                 return;
  761.             }
  762.             if (!$mode_supported) {
  763.                 $this->error =& $this->throwError(
  764.                     DB_TABLE_ERR_CREATE_PHPTYPE,
  765.                     "('$create', '$phptype')"
  766.                 );
  767.                 return;
  768.             }
  769.  
  770.             include_once 'DB/Table/Manager.php';
  771.  
  772.             switch ($create) {
  773.  
  774.                 case 'alter':
  775.                     $result = $this->alter();
  776.                     break;
  777.  
  778.                 case 'drop':
  779.                 case 'safe':
  780.                     $result = $this->create($create);
  781.                     break;
  782.  
  783.                 case 'verify':
  784.                     $result = $this->verify();
  785.                     break;
  786.             }
  787.             
  788.             if (PEAR::isError($result)) {
  789.                 // problem creating/altering/verifing the table
  790.                 $this->error =& $result;
  791.                 return;
  792.             }
  793.         }
  794.     }
  795.     
  796.     
  797.     /**
  798.     * 
  799.     * Is a particular RDBMS supported by DB_Table?
  800.     * 
  801.     * @static
  802.     * 
  803.     * @access public
  804.     * 
  805.     * @param string $phptype The RDBMS type for PHP.
  806.     * 
  807.     * @param string $dbsyntax The chosen database syntax.
  808.     * 
  809.     * @return bool True if supported, false if not.
  810.     * 
  811.     */
  812.     
  813.     function supported($phptype, $dbsyntax = '')
  814.     {
  815.         // only Firebird is supported, not its ancestor Interbase
  816.         if ($phptype == 'ibase' && $dbsyntax != 'firebird') {
  817.             return false;
  818.         }
  819.         $supported = array_keys($GLOBALS['_DB_TABLE']['type']);
  820.         return in_array(strtolower($phptype), $supported);
  821.     }
  822.  
  823.  
  824.     /**
  825.     * 
  826.     * Is a creation mode supported for a RDBMS by DB_Table?
  827.     * 
  828.     * @access public
  829.     * 
  830.     * @param string $mode The chosen creation mode.
  831.     * 
  832.     * @param string $phptype The RDBMS type for PHP.
  833.     * 
  834.     * @return bool|object True if supported, false if not, or a PEAR_Error
  835.     * if an unknown mode is specified.
  836.     * 
  837.     */
  838.     
  839.     function modeSupported($mode, $phptype)
  840.     {
  841.         // check phptype for validity
  842.         $supported = array_keys($GLOBALS['_DB_TABLE']['type']);
  843.         if (!in_array(strtolower($phptype), $supported)) {
  844.             return false;
  845.         }
  846.  
  847.         switch ($mode) {
  848.             case 'drop':
  849.             case 'safe':
  850.                 // supported for all RDBMS
  851.                 return true;
  852.  
  853.             case 'alter':
  854.             case 'verify':
  855.                 // not supported for fbsql and mssql (yet)
  856.                 switch ($phptype) {
  857.                     case 'fbsql':
  858.                     case 'mssql':
  859.                         return false;
  860.                     default:
  861.                         return true;
  862.                 }
  863.  
  864.             default:
  865.                 // unknown creation mode
  866.                 return $this->throwError(
  867.                     DB_TABLE_ERR_CREATE_FLAG,
  868.                     "('$mode')"
  869.                 );
  870.         }
  871.     }
  872.  
  873.  
  874.     /**
  875.     * 
  876.     * Detect values of 'phptype' and 'dbsyntax' keys of DSN.
  877.     * 
  878.     * @static
  879.     * 
  880.     * @access public
  881.     * 
  882.     * @param object &$db A PEAR DB/MDB2 object.
  883.     * 
  884.     * @return array Values of 'phptype' and 'dbsyntax' keys of DSN.
  885.     * 
  886.     */
  887.  
  888.     function getPHPTypeAndDBSyntax(&$db) {
  889.         $phptype = '';
  890.         $dbsyntax = '';
  891.         if (is_subclass_of($db, 'db_common')) {
  892.             $phptype = $db->phptype;
  893.             $dbsyntax = $db->dbsyntax;
  894.         } elseif (is_subclass_of($db, 'mdb2_driver_common')) {
  895.             $dsn = MDB2::parseDSN($db->getDSN());
  896.             $phptype = $dsn['phptype'];
  897.             $dbsyntax = $dsn['dbsyntax'];
  898.         }
  899.         return array($phptype, $dbsyntax);
  900.     }
  901.  
  902.  
  903.     /**
  904.     * 
  905.     * Overwrite one or more error messages, e.g. to internationalize them.
  906.     * 
  907.     * @access public
  908.     * 
  909.     * @param mixed $code If string, the error message with code $code will
  910.     * be overwritten by $message. If array, the error messages with code
  911.     * of each array key will be overwritten by the key's value.
  912.     * 
  913.     * @param string $message Only used if $key is not an array.
  914.     *
  915.     * @return void
  916.     * 
  917.     */
  918.  
  919.     function setErrorMessage($code, $message = null) {
  920.         if (is_array($code)) {
  921.             foreach ($code as $single_code => $single_message) {
  922.                 $GLOBALS['_DB_TABLE']['error'][$single_code] = $single_message;
  923.             }
  924.         } else {
  925.             $GLOBALS['_DB_TABLE']['error'][$code] = $message;
  926.         }
  927.     }
  928.  
  929.  
  930.     /**
  931.     * 
  932.     * Returns all or part of the $this->col property array.
  933.     * 
  934.     * @access public
  935.     * 
  936.     * @param mixed $col If null, returns the $this->col property array
  937.     * as it is.  If string, returns that column name from the $this->col
  938.     * array. If an array, returns those columns named as the array
  939.     * values from the $this->col array as an array.
  940.     *
  941.     * @return mixed All or part of the $this->col property array, or
  942.     * boolean false if no matching column names are found.
  943.     * 
  944.     */
  945.     
  946.     function getColumns($col = null)
  947.     {
  948.         // by default, return all column definitions
  949.         if (is_null($col)) {
  950.             return $this->col;
  951.         }
  952.         
  953.         // if the param is a string, only return the column definition
  954.         // named by the that string
  955.         if (is_string($col)) {
  956.             if (isset($this->col[$col])) {
  957.                 return $this->col[$col];
  958.             } else {
  959.                 return false;
  960.             }
  961.         }
  962.         
  963.         // if the param is a sequential array of column names,
  964.         // return only those columns named in that array
  965.         if (is_array($col)) {
  966.             $set = array();
  967.             foreach ($col as $name) {
  968.                 $set[$name] = $this->getColumns($name);
  969.             }
  970.             
  971.             if (count($set) == 0) {
  972.                 return false;
  973.             } else {
  974.                 return $set;
  975.             }
  976.         }
  977.         
  978.         // param was not null, string, or array
  979.         return false;
  980.     }
  981.     
  982.     
  983.     /**
  984.     * 
  985.     * Returns all or part of the $this->idx property array.
  986.     * 
  987.     * @access public
  988.     * 
  989.     * @param string $col If specified, returns only this index key
  990.     * from the $this->col property array.
  991.     * 
  992.     * @return array All or part of the $this->idx property array.
  993.     * 
  994.     */
  995.     
  996.     function getIndexes($idx = null)
  997.     {
  998.         // by default, return all index definitions
  999.         if (is_null($idx)) {
  1000.             return $this->idx;
  1001.         }
  1002.         
  1003.         // if the param is a string, only return the index definition
  1004.         // named by the that string
  1005.         if (is_string($idx)) {
  1006.             if (isset($this->idx[$idx])) {
  1007.                 return $this->idx[$idx];
  1008.             } else {
  1009.                 return false;
  1010.             }
  1011.         }
  1012.         
  1013.         // if the param is a sequential array of index names,
  1014.         // return only those indexes named in that array
  1015.         if (is_array($idx)) {
  1016.             $set = array();
  1017.             foreach ($idx as $name) {
  1018.                 $set[$name] = $this->getIndexes($name);
  1019.             }
  1020.             
  1021.             if (count($set) == 0) {
  1022.                 return false;
  1023.             } else {
  1024.                 return $set;
  1025.             }
  1026.         }
  1027.         
  1028.         // param was not null, string, or array
  1029.         return false;
  1030.     }
  1031.     
  1032.     
  1033.     /**
  1034.     *
  1035.     * Selects rows from the table using one of the DB/MDB2 get*() methods.
  1036.     * 
  1037.     * @access public
  1038.     * 
  1039.     * @param string $sqlkey The name of the SQL SELECT to use from the
  1040.     * $this->sql property array.
  1041.     * 
  1042.     * @param string $filter Ad-hoc SQL snippet to AND with the default
  1043.     * SELECT WHERE clause.
  1044.     * 
  1045.     * @param string $order Ad-hoc SQL snippet to override the default
  1046.     * SELECT ORDER BY clause.
  1047.     * 
  1048.     * @param int $start The row number to start listing from in the
  1049.     * result set.
  1050.     * 
  1051.     * @param int $count The number of rows to list in the result set.
  1052.     *
  1053.     * @param array $params Parameters to use in placeholder substitutions (if
  1054.     * any).
  1055.     * 
  1056.     * @return mixed An array of records from the table (if anything but
  1057.     * 'getOne'), a single value (if 'getOne'), or a PEAR_Error object.
  1058.     *
  1059.     * @see DB::getAll()
  1060.     * 
  1061.     * @see MDB2::getAll()
  1062.     *
  1063.     * @see DB::getAssoc()
  1064.     * 
  1065.     * @see MDB2::getAssoc()
  1066.     *
  1067.     * @see DB::getCol()
  1068.     * 
  1069.     * @see MDB2::getCol()
  1070.     *
  1071.     * @see DB::getOne()
  1072.     *
  1073.     * @see MDB2::getOne()
  1074.     * 
  1075.     * @see DB::getRow()
  1076.     * 
  1077.     * @see MDB2::getRow()
  1078.     *
  1079.     * @see DB_Table::_swapModes()
  1080.     *
  1081.     */
  1082.     
  1083.     function select($sqlkey, $filter = null, $order = null,
  1084.         $start = null, $count = null, $params = array())
  1085.     {
  1086.         // build the base command
  1087.         $sql = $this->buildSQL($sqlkey, $filter, $order, $start, $count);
  1088.         if (PEAR::isError($sql)) {
  1089.             return $sql;
  1090.         }
  1091.         
  1092.         // set the get*() method name
  1093.         if (isset($this->sql[$sqlkey]['get'])) {
  1094.             $method = ucwords(strtolower(trim($this->sql[$sqlkey]['get'])));
  1095.             $method = "get$method";
  1096.         } else {
  1097.             $method = 'getAll';
  1098.         }
  1099.         
  1100.         // DB_Table assumes you are using a shared PEAR DB/MDB2 object. Other
  1101.         // scripts using the same object probably expect its fetchmode
  1102.         // not to change, unless they change it themselves.  Thus, to
  1103.         // provide friendly mode-swapping, we will restore these modes
  1104.         // afterwards.
  1105.         $restore_mode = $this->db->fetchmode;
  1106.         if ($this->backend == 'mdb2') {
  1107.             $restore_class = $this->db->getOption('fetch_class');
  1108.         } else {
  1109.             $restore_class = $this->db->fetchmode_object_class;
  1110.         }
  1111.         // swap modes
  1112.         $fetchmode = $this->fetchmode;
  1113.         $fetchmode_object_class = $this->fetchmode_object_class;
  1114.         if (isset($this->sql[$sqlkey]['fetchmode'])) {
  1115.             $fetchmode = $this->sql[$sqlkey]['fetchmode'];
  1116.         }
  1117.         if (isset($this->sql[$sqlkey]['fetchmode_object_class'])) {
  1118.             $fetchmode_object_class = $this->sql[$sqlkey]['fetchmode_object_class'];
  1119.         }
  1120.         $this->_swapModes($fetchmode, $fetchmode_object_class);
  1121.  
  1122.         // make sure params is an array
  1123.         if (! is_null($params)) {
  1124.             $params = (array) $params;
  1125.         }
  1126.         
  1127.         // get the result
  1128.         if ($this->backend == 'mdb2') {
  1129.             $result = $this->db->extended->$method($sql, null, $params);
  1130.         } else {
  1131.             switch ($method) {
  1132.  
  1133.                 case 'getCol':
  1134.                     $result = $this->db->$method($sql, 0, $params);
  1135.                     break;
  1136.  
  1137.                 case 'getAssoc':
  1138.                     $result = $this->db->$method($sql, false, $params);
  1139.                     break;
  1140.  
  1141.                 default:
  1142.                     $result = $this->db->$method($sql, $params);
  1143.                     break;
  1144.  
  1145.             }
  1146.         }
  1147.             
  1148.         // swap modes back
  1149.         $this->_swapModes($restore_mode, $restore_class);
  1150.         
  1151.         // return the result
  1152.         return $result;
  1153.     }
  1154.     
  1155.     
  1156.     /**
  1157.     *
  1158.     * Selects rows from the table as a DB_Result/MDB2_Result_* object.
  1159.     * 
  1160.     * @access public
  1161.     * 
  1162.     * @param string $sqlkey The name of the SQL SELECT to use from the
  1163.     * $this->sql property array.
  1164.     * 
  1165.     * @param string $filter Ad-hoc SQL snippet to add to the default
  1166.     * SELECT WHERE clause.
  1167.     * 
  1168.     * @param string $order Ad-hoc SQL snippet to override the default
  1169.     * SELECT ORDER BY clause.
  1170.     * 
  1171.     * @param int $start The record number to start listing from in the
  1172.     * result set.
  1173.     * 
  1174.     * @param int $count The number of records to list in the result set.
  1175.     * 
  1176.     * @param array $params Parameters to use in placeholder substitutions (if
  1177.     * any).
  1178.     * 
  1179.     * @return mixed A PEAR_Error on failure, or a DB_Result/MDB2_Result_*
  1180.     * object on success.
  1181.     *
  1182.     * @see DB_Table::_swapModes()
  1183.     *
  1184.     */
  1185.     
  1186.     function selectResult($sqlkey, $filter = null, $order = null, 
  1187.         $start = null, $count = null, $params = array())
  1188.     {
  1189.         // build the base command
  1190.         $sql = $this->buildSQL($sqlkey, $filter, $order, $start, $count);
  1191.         if (PEAR::isError($sql)) {
  1192.             return $sql;
  1193.         }
  1194.         
  1195.         // DB_Table assumes you are using a shared PEAR DB/MDB2 object.  Other
  1196.         // scripts using the same object probably expect its fetchmode
  1197.         // not to change, unless they change it themselves.  Thus, to
  1198.         // provide friendly mode-swapping, we will restore these modes
  1199.         // afterwards.
  1200.         $restore_mode = $this->db->fetchmode;
  1201.         if ($this->backend == 'mdb2') {
  1202.             $restore_class = $this->db->getOption('fetch_class');
  1203.         } else {
  1204.             $restore_class = $this->db->fetchmode_object_class;
  1205.         }
  1206.         
  1207.         // swap modes
  1208.         $fetchmode = $this->fetchmode;
  1209.         $fetchmode_object_class = $this->fetchmode_object_class;
  1210.         if (isset($this->sql[$sqlkey]['fetchmode'])) {
  1211.             $fetchmode = $this->sql[$sqlkey]['fetchmode'];
  1212.         }
  1213.         if (isset($this->sql[$sqlkey]['fetchmode_object_class'])) {
  1214.             $fetchmode_object_class = $this->sql[$sqlkey]['fetchmode_object_class'];
  1215.         }
  1216.         $this->_swapModes($fetchmode, $fetchmode_object_class);
  1217.         
  1218.         // make sure params is an array
  1219.         if (! is_null($params)) {
  1220.             $params = (array) $params;
  1221.         }
  1222.      
  1223.         // get the result
  1224.         if ($this->backend == 'mdb2') {
  1225.             $stmt =& $this->db->prepare($sql);
  1226.             $result =& $stmt->execute($params);
  1227.         } else {
  1228.             $result =& $this->db->query($sql, $params);
  1229.         }
  1230.         
  1231.         // swap modes back
  1232.         $this->_swapModes($restore_mode, $restore_class);
  1233.         
  1234.         // return the result
  1235.         return $result;
  1236.     }
  1237.     
  1238.     
  1239.     /**
  1240.     *
  1241.     * Counts the number of rows which will be returned by a query.
  1242.     *
  1243.     * This function works identically to {@link select()}, but it
  1244.     * returns the number of rows returned by a query instead of the
  1245.     * query results themselves.
  1246.     *
  1247.     * This makes using DB_Table with Pager easier, since you can pass the
  1248.     * return value of this to Pager as totalItems, then select only the
  1249.     * rows you need to display on a page.
  1250.     *
  1251.     * @author Ian Eure <ian@php.net>
  1252.     * 
  1253.     * @access public
  1254.     * 
  1255.     * @param string $sqlkey The name of the SQL SELECT to use from the
  1256.     * $this->sql property array.
  1257.     * 
  1258.     * @param string $filter Ad-hoc SQL snippet to AND with the default
  1259.     * SELECT WHERE clause.
  1260.     * 
  1261.     * @param string $order Ad-hoc SQL snippet to override the default
  1262.     * SELECT ORDER BY clause.
  1263.     * 
  1264.     * @param int $start The row number to start listing from in the
  1265.     * result set.
  1266.     * 
  1267.     * @param int $count The number of rows to list in the result set.
  1268.     * 
  1269.     * @param array $params Parameters to use in placeholder substitutions (if
  1270.     * any).
  1271.     * 
  1272.     * @return mixed An integer number of records from the table, or a
  1273.     * PEAR_Error object.
  1274.     *
  1275.     * @see DB_Table::select()
  1276.     *
  1277.     */
  1278.     
  1279.     function selectCount($sqlkey, $filter = null, $order = null,
  1280.         $start = null, $count = null, $params = array())
  1281.     {
  1282.         // does the SQL SELECT key exist?
  1283.         $tmp = array_keys($this->sql);
  1284.         if (! in_array($sqlkey, $tmp)) {
  1285.             return $this->throwError(
  1286.                 DB_TABLE_ERR_SQL_UNDEF,
  1287.                 "('$sqlkey')"
  1288.             );
  1289.         }
  1290.         
  1291.         // create a SQL key name for this count-query
  1292.         $count_key = '__count_' . $sqlkey;
  1293.         
  1294.         // has a count-query for the SQL key already been created?
  1295.         if (! isset($this->sql[$count_key])) {
  1296.             
  1297.             // we've not asked for a count on this query yet.
  1298.             // get the elements of the query ...
  1299.             $count_sql = $this->sql[$sqlkey];
  1300.             
  1301.             // is a count-field set for the query?
  1302.             if (! isset($count_sql['count']) ||
  1303.                 trim($count_sql['count']) == '') {
  1304.                 $count_sql['count'] = '*';
  1305.             }
  1306.             
  1307.             // replace the SELECT fields with a COUNT() command
  1308.             $count_sql['select'] = "COUNT({$count_sql['count']})";
  1309.             
  1310.             // replace the 'get' key so we only get the one result item
  1311.             $count_sql['get'] = 'one';
  1312.             
  1313.             // create the new count-query in the $sql array
  1314.             $this->sql[$count_key] = $count_sql;
  1315.         }
  1316.         
  1317.         // retrieve the count results
  1318.         return $this->select($count_key, $filter, $order, $start, $count,
  1319.             $params);
  1320.     }
  1321.     
  1322.     
  1323.     /**
  1324.     * 
  1325.     * Changes the $this->db PEAR DB/MDB2 object fetchmode and
  1326.     * fetchmode_object_class.
  1327.     * 
  1328.     * Because DB_Table objects tend to use the same PEAR DB/MDB2 object, it
  1329.     * may sometimes be useful to have one object return results in one
  1330.     * mode, and have another object return results in a different mode. 
  1331.     * This method allows us to switch DB/MDB2 fetch modes on the fly.
  1332.     * 
  1333.     * @access private
  1334.     * 
  1335.     * @param string $new_mode A DB_FETCHMODE_* constant.  If null,
  1336.     * defaults to whatever the DB/MDB2 object is currently using.
  1337.     * 
  1338.     * @param string $new_class The object class to use for results when
  1339.     * the $db object is in DB_FETCHMODE_OBJECT fetch mode.  If null,
  1340.     * defaults to whatever the the DB/MDB2 object is currently using.
  1341.     * 
  1342.     * @return void
  1343.     * 
  1344.     */
  1345.     
  1346.     function _swapModes($new_mode, $new_class)
  1347.     {
  1348.         // get the old (current) mode and class
  1349.         $old_mode = $this->db->fetchmode;
  1350.         if ($this->backend == 'mdb2') {
  1351.             $old_class = $this->db->getOption('fetch_class');
  1352.         } else {
  1353.             $old_class = $this->db->fetchmode_object_class;
  1354.         }
  1355.         
  1356.         // don't need to swap anything if the new modes are both
  1357.         // null or if the old and new modes already match.
  1358.         if ((is_null($new_mode) && is_null($new_class)) ||
  1359.             ($old_mode == $new_mode && $old_class == $new_class)) {
  1360.             return;
  1361.         }
  1362.         
  1363.         // set the default new mode
  1364.         if (is_null($new_mode)) {
  1365.             $new_mode = $old_mode;
  1366.         }
  1367.         
  1368.         // set the default new class
  1369.         if (is_null($new_class)) {
  1370.             $new_class = $old_class;
  1371.         }
  1372.         
  1373.         // swap modes
  1374.         $this->db->setFetchMode($new_mode, $new_class);
  1375.     }
  1376.     
  1377.     
  1378.     /**
  1379.     * 
  1380.     * Builds the SQL command from a specified $this->sql element.
  1381.     * 
  1382.     * @access public
  1383.     * 
  1384.     * @param string $sqlkey The $this->sql key to use as the basis for the
  1385.     * SQL query string.
  1386.     * 
  1387.     * @param string $filter A filter to add to the WHERE clause of the
  1388.     * defined SELECT in $this->sql.
  1389.     * 
  1390.     * @param string $order An ORDER clause to override the defined order
  1391.     * in $this->sql.
  1392.     * 
  1393.     * @param int $start The row number to start listing from in the
  1394.     * result set.
  1395.     * 
  1396.     * @param int $count The number of rows to list in the result set.
  1397.     * 
  1398.     * @return mixed A PEAR_Error on failure, or an SQL command string on
  1399.     * success.
  1400.     * 
  1401.     */
  1402.     
  1403.     function buildSQL($sqlkey, $filter = null, $order = null,
  1404.         $start = null, $count = null)
  1405.     {
  1406.         // does the SQL SELECT key exist?
  1407.         if (is_null($this->sql)) {
  1408.             $this->sql = array();
  1409.         }
  1410.         $tmp = array_keys($this->sql);
  1411.         if (! in_array($sqlkey, $tmp)) {
  1412.             return $this->throwError(
  1413.                 DB_TABLE_ERR_SQL_UNDEF,
  1414.                 "('$sqlkey')"
  1415.             );
  1416.         }
  1417.         
  1418.         // the SQL clause parts and their default values
  1419.         $part = array(
  1420.             'select' => '*',
  1421.             'from'   => $this->table,
  1422.             'join'   => null,
  1423.             'where'  => null,
  1424.             'group'  => null,
  1425.             'having' => null,
  1426.             'order'  => null
  1427.         );
  1428.         
  1429.         // loop through each possible clause
  1430.         foreach ($part as $key => $val) {
  1431.             if (! isset($this->sql[$sqlkey][$key])) {
  1432.                 continue;
  1433.             } else {
  1434.                 $part[$key] = $this->sql[$sqlkey][$key];
  1435.             }
  1436.         }
  1437.         
  1438.         // add the filter to the WHERE part
  1439.         if ($filter) {
  1440.             if (! $part['where']) {
  1441.                 $part['where'] .= $filter;
  1442.             } else {
  1443.                 $part['where'] .= " AND ($filter)";
  1444.             }
  1445.         }
  1446.         
  1447.         // override the ORDER part
  1448.         if ($order) {
  1449.             $part['order'] = $order;
  1450.         }
  1451.         
  1452.         // build up the command string form the parts
  1453.         $cmd = '';
  1454.         foreach ($part as $key => $val) {
  1455.             
  1456.             // if the part value has not been set, skip it
  1457.             if (! $val) {
  1458.                 continue;
  1459.             }
  1460.             
  1461.             switch ($key) {
  1462.             
  1463.             case 'join':
  1464.                 $cmd .= " $val\n";
  1465.                 break;
  1466.                 
  1467.             case 'group':
  1468.             case 'order':
  1469.                 $cmd .= strtoupper($key) . " BY $val\n";
  1470.                 break;
  1471.                 
  1472.             default:
  1473.                 $cmd .= strtoupper($key) . " $val\n";
  1474.                 break;
  1475.             
  1476.             }
  1477.         }
  1478.         
  1479.         // add LIMIT if requested
  1480.         if (! is_null($start) && ! is_null($count)) {
  1481.             if ($this->backend == 'mdb2') {
  1482.                 $this->db->setLimit($count, $start);
  1483.             } else {
  1484.                 $cmd = $this->db->modifyLimitQuery(
  1485.                     $cmd, $start, $count);
  1486.             }
  1487.         }
  1488.         
  1489.         return $cmd;
  1490.     }
  1491.     
  1492.     
  1493.     /**
  1494.     *
  1495.     * Inserts a single table row after validating through validInsert().
  1496.     * 
  1497.     * @access public
  1498.     * 
  1499.     * @param array $data An associative array of key-value pairs where
  1500.     * the key is the column name and the value is the column value.  This
  1501.     * is the data that will be inserted into the table.  Data is checked
  1502.     * against the column data type for validity.
  1503.     * 
  1504.     * @return mixed Void on success, a PEAR_Error object on failure.
  1505.     *
  1506.     * @see validInsert()
  1507.     * 
  1508.     * @see DB::autoExecute()
  1509.     * 
  1510.     * @see MDB2::autoExecute()
  1511.     * 
  1512.     */
  1513.         
  1514.     function insert($data)
  1515.     {
  1516.         // forcibly recast the data elements to their proper types?
  1517.         if ($this->_auto_recast) {
  1518.             $this->recast($data);
  1519.         }
  1520.         
  1521.         // validate the data if auto-validation is turned on
  1522.         if ($this->_valid_insert) {
  1523.             $result = $this->validInsert($data);
  1524.             if (PEAR::isError($result)) {
  1525.                 return $result;
  1526.             }
  1527.         }
  1528.         if ($this->backend == 'mdb2') {
  1529.             $result = $this->db->extended->autoExecute($this->table, $data,
  1530.                 MDB2_AUTOQUERY_INSERT);
  1531.         } else {
  1532.             $result = $this->db->autoExecute($this->table, $data,
  1533.                 DB_AUTOQUERY_INSERT);
  1534.         }
  1535.         return $result;
  1536.     }
  1537.     
  1538.     
  1539.     /**
  1540.     * 
  1541.     * Turns on (or off) automatic validation of inserted data.
  1542.     * 
  1543.     * @access public
  1544.     * 
  1545.     * @param bool $flag True to turn on auto-validation, false to turn it off.
  1546.     * 
  1547.     * @return void
  1548.     * 
  1549.     */
  1550.     
  1551.     function autoValidInsert($flag = true)
  1552.     {
  1553.         if ($flag) {
  1554.             $this->_valid_insert = true;
  1555.         } else {
  1556.             $this->_valid_insert = false;
  1557.         }
  1558.     }
  1559.     
  1560.     
  1561.     /**
  1562.     *
  1563.     * Validates an array for insertion into the table.
  1564.     * 
  1565.     * @access public
  1566.     * 
  1567.     * @param array $data An associative array of key-value pairs where
  1568.     * the key is the column name and the value is the column value.  This
  1569.     * is the data that will be inserted into the table.  Data is checked
  1570.     * against the column data type for validity.
  1571.     * 
  1572.     * @return mixed Boolean true on success, a PEAR_Error object on
  1573.     * failure.
  1574.     *
  1575.     * @see insert()
  1576.     * 
  1577.     */
  1578.         
  1579.     function validInsert(&$data)
  1580.     {
  1581.         // loop through the data, and disallow insertion of unmapped
  1582.         // columns
  1583.         foreach ($data as $col => $val) {
  1584.             if (! isset($this->col[$col])) {
  1585.                 return $this->throwError(
  1586.                     DB_TABLE_ERR_INS_COL_NOMAP,
  1587.                     "('$col')"
  1588.                 );
  1589.             }
  1590.         }
  1591.         
  1592.         // loop through each column mapping, and check the data to be
  1593.         // inserted into it against the column data type. we loop through
  1594.         // column mappings instead of the insert data to make sure that
  1595.         // all necessary columns are being inserted.
  1596.         foreach ($this->col as $col => $val) {
  1597.             
  1598.             // is the value allowed to be null?
  1599.             if (isset($val['require']) &&
  1600.                 $val['require'] == true &&
  1601.                 (! isset($data[$col]) || is_null($data[$col]))) {
  1602.                 return $this->throwError(
  1603.                     DB_TABLE_ERR_INS_COL_REQUIRED,
  1604.                     "'$col'"
  1605.                 );
  1606.             }
  1607.             
  1608.             // does the value to be inserted match the column data type?
  1609.             if (isset($data[$col]) &&
  1610.                 ! $this->isValid($data[$col], $col)) {
  1611.                 return $this->throwError(
  1612.                     DB_TABLE_ERR_INS_DATA_INVALID,
  1613.                     "'$col' ('$data[$col]')"
  1614.                 );
  1615.             }
  1616.         }
  1617.         
  1618.         return true;
  1619.     }
  1620.     
  1621.     
  1622.     /**
  1623.     *
  1624.     * Updates table row(s) matching a custom WHERE clause, after checking
  1625.     * against validUpdate().
  1626.     * 
  1627.     * @access public
  1628.     * 
  1629.     * @param array $data An associative array of key-value pairs where
  1630.     * the key is the column name and the value is the column value.  These
  1631.     * are the columns that will be updated with new values.
  1632.     * 
  1633.     * @param string $where An SQL WHERE clause limiting which records
  1634.     * are to be updated.
  1635.     * 
  1636.     * @return mixed Void on success, a PEAR_Error object on failure.
  1637.     *
  1638.     * @see validUpdate()
  1639.     *
  1640.     * @see DB::autoExecute()
  1641.     * 
  1642.     * @see MDB2::autoExecute()
  1643.     * 
  1644.     */
  1645.     
  1646.     function update($data, $where)
  1647.     {
  1648.         // forcibly recast the data elements to their proper types?
  1649.         if ($this->_auto_recast) {
  1650.             $this->recast($data);
  1651.         }
  1652.         
  1653.         // validate the data if auto-validation is turned on
  1654.         if ($this->_valid_update) {
  1655.             $result = $this->validUpdate($data);
  1656.             if (PEAR::isError($result)) {
  1657.                 return $result;
  1658.             }
  1659.         }
  1660.         
  1661.         if ($this->backend == 'mdb2') {
  1662.             $result = $this->db->extended->autoExecute($this->table, $data,
  1663.                 MDB2_AUTOQUERY_UPDATE, $where);
  1664.         } else {
  1665.             $result = $this->db->autoExecute($this->table, $data,
  1666.                 DB_AUTOQUERY_UPDATE, $where);
  1667.         }
  1668.         return $result;
  1669.  
  1670.     }
  1671.     
  1672.     
  1673.     /**
  1674.     * 
  1675.     * Turns on (or off) automatic validation of updated data.
  1676.     * 
  1677.     * @access public
  1678.     * 
  1679.     * @param bool $flag True to turn on auto-validation, false to turn it off.
  1680.     * 
  1681.     * @return void
  1682.     * 
  1683.     */
  1684.     
  1685.     function autoValidUpdate($flag = true)
  1686.     {
  1687.         if ($flag) {
  1688.             $this->_valid_update = true;
  1689.         } else {
  1690.             $this->_valid_update = false;
  1691.         }
  1692.     }
  1693.     
  1694.     
  1695.     /**
  1696.     *
  1697.     * Validates an array for updating the table.
  1698.     * 
  1699.     * @access public
  1700.     * 
  1701.     * @param array $data An associative array of key-value pairs where
  1702.     * the key is the column name and the value is the column value.  This
  1703.     * is the data that will be inserted into the table.  Data is checked
  1704.     * against the column data type for validity.
  1705.     * 
  1706.     * @return mixed Boolean true on success, a PEAR_Error object on
  1707.     * failure.
  1708.     *
  1709.     * @see update()
  1710.     * 
  1711.     */
  1712.         
  1713.     function validUpdate(&$data)
  1714.     {
  1715.         // loop through each data element, and check the
  1716.         // data to be updated against the column data type.
  1717.         foreach ($data as $col => $val) {
  1718.             
  1719.             // does the column exist?
  1720.             if (! isset($this->col[$col])) {
  1721.                 return $this->throwError(
  1722.                     DB_TABLE_ERR_UPD_COL_NOMAP,
  1723.                     "('$col')"
  1724.                 );
  1725.             }
  1726.             
  1727.             // the column definition
  1728.             $defn = $this->col[$col];
  1729.             
  1730.             // is it allowed to be null?
  1731.             if (isset($defn['require']) &&
  1732.                 $defn['require'] == true &&
  1733.                 isset($data[$col]) &&
  1734.                 is_null($data[$col])) {
  1735.                 return $this->throwError(
  1736.                     DB_TABLE_ERR_UPD_COL_REQUIRED,
  1737.                     $col
  1738.                 );
  1739.             }
  1740.             
  1741.             // does the value to be inserted match the column data type?
  1742.             if (! $this->isValid($data[$col], $col)) {
  1743.                 return $this->throwError(
  1744.                     DB_TABLE_ERR_UPD_DATA_INVALID,
  1745.                     "$col ('$data[$col]')"
  1746.                 );
  1747.             }
  1748.         }
  1749.         
  1750.         return true;
  1751.     }
  1752.     
  1753.     
  1754.     /**
  1755.     *
  1756.     * Deletes table rows matching a custom WHERE clause.
  1757.     * 
  1758.     * @access public
  1759.     * 
  1760.     * @param string $where The WHERE clause for the delete command.
  1761.     *
  1762.     * @return mixed Void on success or a PEAR_Error object on failure.
  1763.     *
  1764.     * @see DB::query()
  1765.     * 
  1766.     * @see MDB2::exec()
  1767.     * 
  1768.     */
  1769.     
  1770.     function delete($where)
  1771.     {
  1772.         if ($this->backend == 'mdb2') {
  1773.             $result = $this->db->exec("DELETE FROM $this->table WHERE $where");
  1774.         } else {
  1775.             $result = $this->db->query("DELETE FROM $this->table WHERE $where");
  1776.         }
  1777.         return $result;
  1778.     }
  1779.     
  1780.     
  1781.     /**
  1782.     *
  1783.     * Generates a sequence value; sequence name defaults to the table name.
  1784.     * 
  1785.     * @access public
  1786.     * 
  1787.     * @param string $seq_name The sequence name; defaults to table_id.
  1788.     * 
  1789.     * @return integer The next value in the sequence.
  1790.     *
  1791.     * @see DB::nextID()
  1792.     * 
  1793.     * @see MDB2::nextID()
  1794.     *
  1795.     */
  1796.     
  1797.     function nextID($seq_name = null)
  1798.     {
  1799.         if (is_null($seq_name)) {
  1800.             $seq_name = "{$this->table}";
  1801.         } else {
  1802.             $seq_name = "{$this->table}_{$seq_name}";
  1803.         }
  1804.         
  1805.         // the maximum length is 30, but PEAR DB/MDB2 will add "_seq" to the
  1806.         // name, so the max length here is less 4 chars. we have to
  1807.         // check here because the sequence will be created automatically
  1808.         // by PEAR DB/MDB2, which will not check for length on its own.
  1809.         if (strlen($seq_name) > 26) {
  1810.             return DB_Table::throwError(
  1811.                 DB_TABLE_ERR_SEQ_STRLEN,
  1812.                 " ('$seq_name')"
  1813.             );
  1814.             
  1815.         }
  1816.         return $this->db->nextId($seq_name);
  1817.     }
  1818.     
  1819.     
  1820.     /**
  1821.     * 
  1822.     * Escapes and enquotes a value for use in an SQL query.
  1823.     * 
  1824.     * Helps makes user input safe against SQL injection attack.
  1825.     * 
  1826.     * @access public
  1827.     * 
  1828.     * @return string The value with quotes escaped, and inside single quotes.
  1829.     * 
  1830.     * @see DB_Common::quoteSmart()
  1831.     * 
  1832.     * @see MDB2::quote()
  1833.     * 
  1834.     */
  1835.     
  1836.     function quote($val)
  1837.     {
  1838.         if ($this->backend == 'mdb2') {
  1839.             $val = $this->db->quote($val);
  1840.         } else {
  1841.             $val = $this->db->quoteSmart($val);
  1842.         }
  1843.         return $val;
  1844.     }
  1845.     
  1846.     
  1847.     /**
  1848.     * 
  1849.     * Returns a blank row array based on the column map.
  1850.     * 
  1851.     * The array keys are the column names, and all values are set to null.
  1852.     * 
  1853.     * @access public
  1854.     * 
  1855.     * @return array An associative array where the key is column name
  1856.     * and the value is null.
  1857.     * 
  1858.     */
  1859.     
  1860.     function getBlankRow()
  1861.     {
  1862.         $row = array();
  1863.         
  1864.         foreach ($this->col as $key => $val) {
  1865.             $row[$key] = null;
  1866.         }
  1867.         
  1868.         $this->recast($row);
  1869.         
  1870.         return $row;
  1871.     }
  1872.     
  1873.     
  1874.     /**
  1875.     * 
  1876.     * Turns on (or off) automatic recasting of insert and update data.
  1877.     * 
  1878.     * @access public
  1879.     * 
  1880.     * @param bool $flag True to autmatically recast insert and update data,
  1881.     * false to not do so.
  1882.     *
  1883.     * @return void
  1884.     * 
  1885.     */
  1886.     
  1887.     function autoRecast($flag = true)
  1888.     {
  1889.         if ($flag) {
  1890.             $this->_auto_recast = true;
  1891.         } else {
  1892.             $this->_auto_recast = false;
  1893.         }
  1894.     }
  1895.     
  1896.     
  1897.     /**
  1898.     * 
  1899.     * Forces array elements to the proper types for their columns.
  1900.     * 
  1901.     * This will not valiate the data, and will forcibly change the data
  1902.     * to match the recast-type.
  1903.     * 
  1904.     * The date, time, and timestamp recasting has special logic for
  1905.     * arrays coming from an HTML_QuickForm object so that the arrays
  1906.     * are converted into properly-formatted strings.
  1907.     * 
  1908.     * @todo If a column key holds an array of values (say from a multiple
  1909.     * select) then this method will not work properly; it will recast the
  1910.     * value to the string 'Array'.  Is this bad?
  1911.     * 
  1912.     * @access public
  1913.     * 
  1914.     * @param array &$data The data array to re-cast.
  1915.     *
  1916.     * @return void
  1917.     * 
  1918.     */
  1919.     
  1920.     function recast(&$data)
  1921.     {
  1922.         $keys = array_keys($data);
  1923.         
  1924.         $null_if_blank = array('date', 'time', 'timestamp', 'smallint',
  1925.             'integer', 'bigint', 'decimal', 'single', 'double');
  1926.         
  1927.         foreach ($keys as $key) {
  1928.         
  1929.             if (! isset($this->col[$key])) {
  1930.                 continue;
  1931.             }
  1932.             
  1933.             unset($val);
  1934.             $val =& $data[$key];
  1935.             
  1936.             // convert blanks to null for non-character field types
  1937.             $convert = in_array($this->col[$key]['type'], $null_if_blank);
  1938.             if (is_array($val)) {  // if one of the given array values is
  1939.                                    // empty, null will be the new value if
  1940.                                    // the field is not required
  1941.                 $tmp_val = implode('', $val);
  1942.                 foreach ($val as $array_val) {
  1943.                     if (trim((string) $array_val) == '') {
  1944.                         $tmp_val = '';
  1945.                         break;
  1946.                     }
  1947.                 }
  1948.             } else {
  1949.                 $tmp_val = $val;
  1950.             }
  1951.             if ($convert && trim((string) $tmp_val) == '' && (
  1952.                 !isset($this->col[$key]['require']) ||
  1953.                 $this->col[$key]['require'] === false
  1954.               )
  1955.             ) {
  1956.                 $val = null;
  1957.             }
  1958.             
  1959.             // skip explicit NULL values
  1960.             if (is_null($val)) {
  1961.                 continue;
  1962.             }
  1963.             
  1964.             // otherwise, recast to the column type
  1965.             switch ($this->col[$key]['type']) {
  1966.             
  1967.             case 'boolean':
  1968.                 $val = ($val) ? 1 : 0;
  1969.                 break;
  1970.                 
  1971.             case 'char':
  1972.             case 'varchar':
  1973.             case 'clob':
  1974.                 settype($val, 'string');
  1975.                 break;
  1976.                 
  1977.             case 'date':
  1978.  
  1979.                 // smart handling of non-standard (i.e. Y-m-d) date formats,
  1980.                 // this allows to use two-digit years (y) and short (M) or
  1981.                 // long (F) names of months without having to recast the
  1982.                 // date value yourself
  1983.                 if (is_array($val)) {
  1984.                     if (isset($val['y'])) {
  1985.                         $val['Y'] = $val['y'];
  1986.                     }
  1987.                     if (isset($val['F'])) {
  1988.                         $val['m'] = $val['F'];
  1989.                     }
  1990.                     if (isset($val['M'])) {
  1991.                         $val['m'] = $val['M'];
  1992.                     }
  1993.                 }
  1994.  
  1995.                 if (is_array($val) &&
  1996.                     isset($val['Y']) &&
  1997.                     isset($val['m']) &&
  1998.                     isset($val['d'])) {
  1999.                     
  2000.                     // the date is in HTML_QuickForm format,
  2001.                     // convert into a string
  2002.                     $y = (strlen($val['Y']) < 4)
  2003.                         ? str_pad($val['Y'], 4, '0', STR_PAD_LEFT)
  2004.                         : $val['Y'];
  2005.                     
  2006.                     $m = (strlen($val['m']) < 2)
  2007.                         ? '0'.$val['m'] : $val['m'];
  2008.                         
  2009.                     $d = (strlen($val['d']) < 2)
  2010.                         ? '0'.$val['d'] : $val['d'];
  2011.                         
  2012.                     $val = "$y-$m-$d";
  2013.                     
  2014.                 } else {
  2015.                 
  2016.                     // convert using the Date class
  2017.                     $tmp =& new DB_Table_Date($val);
  2018.                     $val = $tmp->format('%Y-%m-%d');
  2019.                     
  2020.                 }
  2021.                 
  2022.                 break;
  2023.             
  2024.             case 'time':
  2025.             
  2026.                 if (is_array($val) &&
  2027.                     isset($val['H']) &&
  2028.                     isset($val['i']) &&
  2029.                     isset($val['s'])) {
  2030.                     
  2031.                     // the time is in HTML_QuickForm format,
  2032.                     // convert into a string
  2033.                     $h = (strlen($val['H']) < 2)
  2034.                         ? '0' . $val['H'] : $val['H'];
  2035.                     
  2036.                     $i = (strlen($val['i']) < 2)
  2037.                         ? '0' . $val['i'] : $val['i'];
  2038.                         
  2039.                     $s = (strlen($val['s']) < 2)
  2040.                         ? '0' . $val['s'] : $val['s'];
  2041.                         
  2042.                         
  2043.                     $val = "$h:$i:$s";
  2044.                     
  2045.                 } else {
  2046.                     // date does not matter in this case, so
  2047.                     // pre 1970 and post 2040 are not an issue.
  2048.                     $tmp = strtotime(date('Y-m-d') . " $val");
  2049.                     $val = date('H:i:s', $tmp);
  2050.                 }
  2051.                 
  2052.                 break;
  2053.                 
  2054.             case 'timestamp':
  2055.  
  2056.                 // smart handling of non-standard (i.e. Y-m-d) date formats,
  2057.                 // this allows to use two-digit years (y) and short (M) or
  2058.                 // long (F) names of months without having to recast the
  2059.                 // date value yourself
  2060.                 if (is_array($val)) {
  2061.                     if (isset($val['y'])) {
  2062.                         $val['Y'] = $val['y'];
  2063.                     }
  2064.                     if (isset($val['F'])) {
  2065.                         $val['m'] = $val['F'];
  2066.                     }
  2067.                     if (isset($val['M'])) {
  2068.                         $val['m'] = $val['M'];
  2069.                     }
  2070.                 }
  2071.  
  2072.                 if (is_array($val) &&
  2073.                     isset($val['Y']) &&
  2074.                     isset($val['m']) &&
  2075.                     isset($val['d']) &&
  2076.                     isset($val['H']) &&
  2077.                     isset($val['i']) &&
  2078.                     isset($val['s'])) {
  2079.                     
  2080.                     // timestamp is in HTML_QuickForm format,
  2081.                     // convert each element to a string. pad
  2082.                     // with zeroes as needed.
  2083.                 
  2084.                     $y = (strlen($val['Y']) < 4)
  2085.                         ? str_pad($val['Y'], 4, '0', STR_PAD_LEFT)
  2086.                         : $val['Y'];
  2087.                     
  2088.                     $m = (strlen($val['m']) < 2)
  2089.                         ? '0'.$val['m'] : $val['m'];
  2090.                         
  2091.                     $d = (strlen($val['d']) < 2)
  2092.                         ? '0'.$val['d'] : $val['d'];
  2093.                         
  2094.                     $h = (strlen($val['H']) < 2)
  2095.                         ? '0' . $val['H'] : $val['H'];
  2096.                     
  2097.                     $i = (strlen($val['i']) < 2)
  2098.                         ? '0' . $val['i'] : $val['i'];
  2099.                         
  2100.                     $s = (strlen($val['s']) < 2)
  2101.                         ? '0' . $val['s'] : $val['s'];
  2102.                         
  2103.                     $val = "$y-$m-$d $h:$i:$s";
  2104.                     
  2105.                 } else {
  2106.                     // convert using the Date class
  2107.                     $tmp =& new DB_Table_Date($val);
  2108.                     $val = $tmp->format('%Y-%m-%d %H:%M:%S');
  2109.                 }
  2110.                 
  2111.                 break;
  2112.             
  2113.             case 'smallint':
  2114.             case 'integer':
  2115.             case 'bigint':
  2116.                 settype($val, 'integer');
  2117.                 break;
  2118.             
  2119.             case 'decimal':
  2120.             case 'single':
  2121.             case 'double':
  2122.                 settype($val, 'float');
  2123.                 break;
  2124.  
  2125.             }
  2126.         }
  2127.     }
  2128.     
  2129.     
  2130.     /**
  2131.     * 
  2132.     * Creates the table based on $this->col and $this->idx.
  2133.     * 
  2134.     * @access public
  2135.     * 
  2136.     * @param mixed $flag The automatic table creation mode to pursue:
  2137.     * - 'safe' to create the table only if it does not exist
  2138.     * - 'drop' to drop any existing table with the same name and re-create it
  2139.     * 
  2140.     * @return mixed Boolean false if there was no need to create the
  2141.     * table, boolean true if the attempt succeeded, or a PEAR_Error if
  2142.     * the attempt failed.
  2143.     * 
  2144.     * @see DB_Table_Manager::create()
  2145.     * 
  2146.     */
  2147.     
  2148.     function create($flag)
  2149.     {
  2150.  
  2151.         // are we OK to create the table?
  2152.         $ok = false;
  2153.         
  2154.         // check the create-flag
  2155.         switch ($flag) {
  2156.  
  2157.             case 'drop':
  2158.                 // drop only if table exists
  2159.                 $table_exists = DB_Table_Manager::tableExists($this->db,
  2160.                                                               $this->table);
  2161.                 if (PEAR::isError($table_exists)) {
  2162.                     return $table_exists;
  2163.                 }
  2164.                 if ($table_exists) {
  2165.                     // forcibly drop an existing table
  2166.                     if ($this->backend == 'mdb2') {
  2167.                         $this->db->manager->dropTable($this->table);
  2168.                     } else {
  2169.                         $this->db->query("DROP TABLE {$this->table}");
  2170.                     }
  2171.                 }
  2172.                 $ok = true;
  2173.                 break;
  2174.  
  2175.             case 'safe':
  2176.                 // create only if table does not exist
  2177.                 $table_exists = DB_Table_Manager::tableExists($this->db,
  2178.                                                               $this->table);
  2179.                 if (PEAR::isError($table_exists)) {
  2180.                     return $table_exists;
  2181.                 }
  2182.                 // ok to create only if table does not exist
  2183.                 $ok = !$table_exists;
  2184.                 break;
  2185.  
  2186.         }
  2187.  
  2188.         // are we going to create the table?
  2189.         if (! $ok) {
  2190.             return false;
  2191.         }
  2192.  
  2193.         return DB_Table_Manager::create(
  2194.             $this->db, $this->table, $this->col, $this->idx
  2195.         );
  2196.     }
  2197.     
  2198.     
  2199.     /**
  2200.     * 
  2201.     * Alters the table based on $this->col and $this->idx.
  2202.     * 
  2203.     * @access public
  2204.     * 
  2205.     * @return mixed Boolean true if altering was successful or a PEAR_Error on
  2206.     * failure.
  2207.     *
  2208.     * @see DB_Table_Manager::alter()
  2209.     * 
  2210.     */
  2211.     
  2212.     function alter()
  2213.     {
  2214.         $create = false;
  2215.         
  2216.         // alter the table columns and indexes if the table exists
  2217.         $table_exists = DB_Table_Manager::tableExists($this->db,
  2218.                                                       $this->table);
  2219.         if (PEAR::isError($table_exists)) {
  2220.             return $table_exists;
  2221.         }
  2222.         if (!$table_exists) {
  2223.             // table does not exist => just create the table, there is
  2224.             // nothing that could be altered
  2225.             $create = true;
  2226.         }
  2227.  
  2228.         if ($create) {
  2229.             return DB_Table_Manager::create(
  2230.                 $this->db, $this->table, $this->col, $this->idx
  2231.             );
  2232.         }
  2233.  
  2234.         return DB_Table_Manager::alter(
  2235.             $this->db, $this->table, $this->col, $this->idx
  2236.         );
  2237.     }
  2238.     
  2239.     
  2240.     /**
  2241.     * 
  2242.     * Verifies the table based on $this->col and $this->idx.
  2243.     * 
  2244.     * @access public
  2245.     * 
  2246.     * @return mixed Boolean true if the verification was successful, and a
  2247.     * PEAR_Error if verification failed.
  2248.     *
  2249.     * @see DB_Table_Manager::verify()
  2250.     * 
  2251.     */
  2252.     
  2253.     function verify()
  2254.     {
  2255.         return DB_Table_Manager::verify(
  2256.             $this->db, $this->table, $this->col, $this->idx
  2257.         );
  2258.     }
  2259.     
  2260.     
  2261.     /**
  2262.     * 
  2263.     * Checks if a value validates against the DB_Table data type for a
  2264.     * given column. This only checks that it matches the data type; it
  2265.     * does not do extended validation.
  2266.     * 
  2267.     * @access public
  2268.     * 
  2269.     * @param array $val A value to check against the column's DB_Table
  2270.     * data type.
  2271.     * 
  2272.     * @param array $col A column name from $this->col.
  2273.     * 
  2274.     * @return boolean True if the value validates (matches the
  2275.     * data type), false if not.
  2276.     * 
  2277.     * @see DB_Table_Valid
  2278.     * 
  2279.     */
  2280.     
  2281.     function isValid($val, $col)
  2282.     {
  2283.         // is the value null?
  2284.         if (is_null($val)) {
  2285.             // is the column required?
  2286.             if ($this->isRequired($col)) {
  2287.                 // yes, so not valid
  2288.                 return false;
  2289.             } else {
  2290.                 // not required, so it's valid
  2291.                 return true;
  2292.             }
  2293.         }
  2294.         
  2295.         // make sure we have the validation class
  2296.         include_once 'DB/Table/Valid.php';
  2297.         
  2298.         // validate values per the column type.  we use sqlite
  2299.         // as the single authentic list of allowed column types,
  2300.         // regardless of the actual rdbms being used.
  2301.         $map = array_keys($GLOBALS['_DB_TABLE']['type']['sqlite']);
  2302.         
  2303.         // is the column type on the map?
  2304.         if (! in_array($this->col[$col]['type'], $map)) {
  2305.             return $this->throwError(
  2306.                 DB_TABLE_ERR_VALIDATE_TYPE,
  2307.                 "'$col' ('{$this->col[$col]['type']}')"
  2308.             );
  2309.         }
  2310.         
  2311.         // validate for the type
  2312.         switch ($this->col[$col]['type']) {
  2313.         
  2314.         case 'char':
  2315.         case 'varchar':
  2316.             $result = DB_Table_Valid::isChar(
  2317.                 $val,
  2318.                 $this->col[$col]['size']
  2319.             );
  2320.             break;
  2321.         
  2322.         case 'decimal':
  2323.             $result = DB_Table_Valid::isDecimal(
  2324.                 $val,
  2325.                 $this->col[$col]['size'],
  2326.                 $this->col[$col]['scope']
  2327.             );
  2328.             break;
  2329.             
  2330.         default:
  2331.             $result = call_user_func(
  2332.                 array(
  2333.                     'DB_Table_Valid',
  2334.                     'is' . ucwords($this->col[$col]['type'])
  2335.                 ),
  2336.                 $val
  2337.             );
  2338.             break;
  2339.  
  2340.         }
  2341.         
  2342.         // have we passed the check so far, and should we
  2343.         // also check for allowed values?
  2344.         if ($result && isset($this->col[$col]['qf_vals'])) {
  2345.             $keys = array_keys($this->col[$col]['qf_vals']);
  2346.             
  2347.             $result = in_array(
  2348.                 $val,
  2349.                 array_keys($this->col[$col]['qf_vals'])
  2350.             );
  2351.         }
  2352.         
  2353.         return $result;
  2354.     }
  2355.     
  2356.     
  2357.     /**
  2358.     * 
  2359.     * Is a specific column required to be set and non-null?
  2360.     * 
  2361.     * @access public
  2362.     * 
  2363.     * @param mixed $column The column to check against.
  2364.     * 
  2365.     * @return boolean True if required, false if not.
  2366.     * 
  2367.     */
  2368.     
  2369.     function isRequired($column)
  2370.     {
  2371.         if (isset($this->col[$column]['require']) &&
  2372.             $this->col[$column]['require'] == true) {
  2373.             return true;
  2374.         } else {
  2375.             return false;
  2376.         }
  2377.     }
  2378.     
  2379.     
  2380.     /**
  2381.     * 
  2382.     * Creates and returns a QuickForm object based on table columns.
  2383.     *
  2384.     * @access public
  2385.     *
  2386.     * @param array $columns A sequential array of column names to use in
  2387.     * the form; if null, uses all columns.
  2388.     *
  2389.     * @param string $array_name By default, the form will use the names
  2390.     * of the columns as the names of the form elements.  If you pass
  2391.     * $array_name, the column names will become keys in an array named
  2392.     * for this parameter.
  2393.     * 
  2394.     * @param array $args An associative array of optional arguments to
  2395.     * pass to the QuickForm object.  The keys are...
  2396.     *
  2397.     * 'formName' : String, name of the form; defaults to the name of this
  2398.     * table.
  2399.     * 
  2400.     * 'method' : String, form method; defaults to 'post'.
  2401.     * 
  2402.     * 'action' : String, form action; defaults to
  2403.     * $_SERVER['REQUEST_URI'].
  2404.     * 
  2405.     * 'target' : String, form target target; defaults to '_self'
  2406.     * 
  2407.     * 'attributes' : Associative array, extra attributes for <form>
  2408.     * tag; the key is the attribute name and the value is attribute
  2409.     * value.
  2410.     * 
  2411.     * 'trackSubmit' : Boolean, whether to track if the form was
  2412.     * submitted by adding a special hidden field
  2413.     * 
  2414.     * @param string $clientValidate By default, validation will match
  2415.     * the 'qf_client' value from the column definition.  However,
  2416.     * if you set $clientValidate to true or false, this will
  2417.     * override the value from the column definition.
  2418.     *
  2419.     * @param array $formFilters An array with filter function names or
  2420.     * callbacks that will be applied to all form elements.
  2421.     *
  2422.     * @return object HTML_QuickForm
  2423.     * 
  2424.     * @see HTML_QuickForm
  2425.     * 
  2426.     * @see DB_Table_QuickForm
  2427.     * 
  2428.     */
  2429.     
  2430.     function &getForm($columns = null, $array_name = null, $args = array(),
  2431.         $clientValidate = null, $formFilters = null)
  2432.     {
  2433.         include_once 'DB/Table/QuickForm.php';
  2434.         $coldefs = $this->_getFormColDefs($columns);
  2435.         $form =& DB_Table_QuickForm::getForm($coldefs, $array_name, $args,
  2436.             $clientValidate, $formFilters);
  2437.         return $form;
  2438.     }
  2439.     
  2440.     
  2441.     /**
  2442.     * 
  2443.     * Adds elements and rules to a pre-existing HTML_QuickForm object.
  2444.     * 
  2445.     * @access public
  2446.     * 
  2447.     * @param object &$form An HTML_QuickForm object.
  2448.     * 
  2449.     * @param array $columns A sequential array of column names to use in
  2450.     * the form; if null, uses all columns.
  2451.     *
  2452.     * @param string $array_name By default, the form will use the names
  2453.     * of the columns as the names of the form elements.  If you pass
  2454.     * $array_name, the column names will become keys in an array named
  2455.     * for this parameter.
  2456.     * 
  2457.     * @return void
  2458.     * 
  2459.     * @see HTML_QuickForm
  2460.     * 
  2461.     * @see DB_Table_QuickForm
  2462.     * 
  2463.     */
  2464.     
  2465.     function addFormElements(&$form, $columns = null, $array_name = null,
  2466.         $clientValidate = null)
  2467.     {
  2468.         include_once 'DB/Table/QuickForm.php';
  2469.         $coldefs = $this->_getFormColDefs($columns);
  2470.         DB_Table_QuickForm::addElements($form, $coldefs, $array_name);
  2471.         DB_Table_QuickForm::addRules($form, $coldefs, $array_name,
  2472.             $clientValidate);
  2473.     }
  2474.  
  2475.  
  2476.     /**
  2477.     * 
  2478.     * Adds static form elements like 'header', 'static', 'submit' or 'reset' to
  2479.     * a pre-existing HTML_QuickForm object. The form elements needs to be
  2480.     * defined in a property called $frm.
  2481.     * 
  2482.     * @access public
  2483.     * 
  2484.     * @param object &$form An HTML_QuickForm object.
  2485.     * 
  2486.     * @return void
  2487.     * 
  2488.     * @see HTML_QuickForm
  2489.     * 
  2490.     * @see DB_Table_QuickForm
  2491.     * 
  2492.     */
  2493.  
  2494.     function addStaticFormElements(&$form)
  2495.     {
  2496.         include_once 'DB/Table/QuickForm.php';
  2497.         DB_Table_QuickForm::addStaticElements($form, $this->frm);
  2498.     }
  2499.  
  2500.  
  2501.     /**
  2502.     * 
  2503.     * Creates and returns an array of QuickForm elements based on an
  2504.     * array of DB_Table column names.
  2505.     * 
  2506.     * @access public
  2507.     * 
  2508.     * @param array $columns A sequential array of column names to use in
  2509.     * the form; if null, uses all columns.
  2510.     * 
  2511.     * @param string $array_name By default, the form will use the names
  2512.     * of the columns as the names of the form elements.  If you pass
  2513.     * $array_name, the column names will become keys in an array named
  2514.     * for this parameter.
  2515.     * 
  2516.     * @return array An array of HTML_QuickForm_Element objects.
  2517.     * 
  2518.     * @see HTML_QuickForm
  2519.     * 
  2520.     * @see DB_Table_QuickForm
  2521.     * 
  2522.     */
  2523.     
  2524.     function &getFormGroup($columns = null, $array_name = null)
  2525.     {
  2526.         include_once 'DB/Table/QuickForm.php';
  2527.         $coldefs = $this->_getFormColDefs($columns);
  2528.         $group =& DB_Table_QuickForm::getGroup($coldefs, $array_name);
  2529.         return $group;
  2530.     }
  2531.     
  2532.     
  2533.     /**
  2534.     * 
  2535.     * Creates and returns a single QuickForm element based on a DB_Table
  2536.     * column name.
  2537.     * 
  2538.     * @access public
  2539.     * 
  2540.     * @param string $column A DB_Table column name.
  2541.     * 
  2542.     * @param string $elemname The name to use for the generated QuickForm
  2543.     * element.
  2544.     * 
  2545.     * @return object HTML_QuickForm_Element
  2546.     * 
  2547.     * @see HTML_QuickForm
  2548.     * 
  2549.     * @see DB_Table_QuickForm
  2550.     * 
  2551.     */
  2552.     
  2553.     function &getFormElement($column, $elemname)
  2554.     {
  2555.         include_once 'DB/Table/QuickForm.php';
  2556.         $coldef = $this->_getFormColDefs($column);
  2557.         DB_Table_QuickForm::fixColDef($coldef[$column], $elemname);
  2558.         $element =& DB_Table_QuickForm::getElement($coldef[$column],
  2559.             $elemname);
  2560.         return $element;
  2561.     }
  2562.  
  2563.     /**
  2564.     * 
  2565.     * Creates and returns an array of QuickForm elements based on a DB_Table
  2566.     * column name.
  2567.     * 
  2568.     * @author Ian Eure <ieure@php.net>
  2569.     * 
  2570.     * @access public
  2571.     * 
  2572.     * @param array $cols Array of DB_Table column names
  2573.     * 
  2574.     * @param string $array_name The name to use for the generated QuickForm
  2575.     * elements.
  2576.     * 
  2577.     * @return object HTML_QuickForm_Element
  2578.     * 
  2579.     * @see HTML_QuickForm
  2580.     * 
  2581.     * @see DB_Table_QuickForm
  2582.     * 
  2583.     */
  2584.     function &getFormElements($cols, $array_name = null)
  2585.     {
  2586.         include_once 'DB/Table/QuickForm.php';
  2587.         $elements =& DB_Table_QuickForm::getElements($cols, $array_name);
  2588.         return $elements;
  2589.     }
  2590.     
  2591.     
  2592.     /**
  2593.     * 
  2594.     * Creates a column definition array suitable for DB_Table_QuickForm.
  2595.     * 
  2596.     * @access public
  2597.     * 
  2598.     * @param string|array $column_set A string column name, a sequential
  2599.     * array of columns names, or an associative array where the key is a
  2600.     * column name and the value is the default value for the generated
  2601.     * form element.  If null, uses all columns for this class.
  2602.     * 
  2603.     * @return array An array of columne defintions suitable for passing
  2604.     * to DB_Table_QuickForm.
  2605.     * 
  2606.     */
  2607.     
  2608.     function _getFormColDefs($column_set = null)
  2609.     {
  2610.         if (is_null($column_set)) {
  2611.             // no columns or columns+values; just return the $this->col
  2612.             // array.
  2613.             return $this->getColumns($column_set);
  2614.         }
  2615.         
  2616.         // check to see if the keys are sequential integers.  if so,
  2617.         // the $column_set is just a list of columns.
  2618.         settype($column_set, 'array');
  2619.         $keys = array_keys($column_set);
  2620.         $all_integer = true;
  2621.         foreach ($keys as $val) {
  2622.             if (! is_integer($val)) {
  2623.                 $all_integer = false;
  2624.                 break;
  2625.             }
  2626.         }
  2627.         
  2628.         if ($all_integer) {
  2629.         
  2630.             // the column_set is just a list of columns; get back the $this->col
  2631.             // array elements matching this list.
  2632.             $coldefs = $this->getColumns($column_set);
  2633.             
  2634.         } else {
  2635.             
  2636.             // the columns_set is an associative array where the key is a
  2637.             // column name and the value is the form element value.
  2638.             $coldefs = $this->getColumns($keys);
  2639.             foreach ($coldefs as $key => $val) {
  2640.                 $coldefs[$key]['qf_setvalue'] = $column_set[$key];
  2641.             }
  2642.             
  2643.         }
  2644.         
  2645.         return $coldefs;
  2646.     }
  2647.  
  2648. }
  2649. ?>
  2650.